home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / comm2 / rpgbbs3.lha / Documentation / XEMulator < prev    next >
Text File  |  1992-07-15  |  15KB  |  575 lines
  1. TABLE OF CONTENTS
  2.  
  3. xem.library/XEmulatorSetup
  4. xem.library/XEmulatorOpenConsole
  5. xem.library/XEmulatorCloseConsole
  6. xem.library/XEmulatorCleanup
  7. xem.library/XEmulatorWrite
  8. xem.library/XEmulatorSignal
  9. xem.library/XEmulatorHostMon
  10. xem.library/XEmulatorUserMon
  11. xem.library/XEmulatorOptions
  12. xem.library/XEmulatorClearConsole
  13. xem.library/XEmulatorResetConsole
  14. xem.library/XEmulatorResetTextStyles
  15. xem.library/XEmulatorResetCharset
  16. xem.library/XEmulatorGetFreeMacroKeys
  17. xem.library/XEmulatorMacroKeyFilter
  18. xem.library/XEmulatorInfo
  19. xem.library/XEmulatorPreferences
  20.  
  21. xem.library/XEmulatorSetup                         xem.library/XEmulatorSetup
  22.  
  23.    NAME
  24.     XEmulatorSetup -- initializes internal structure used by the emulator
  25.  
  26.    SYNOPSIS
  27.     result = XEmulatorSetup(xem_io)
  28.     D0            A0
  29.  
  30.     BOOL XEmulatorSetup(struct XEM_IO *);
  31.  
  32.    FUNCTION
  33.     Before a comm-proggy calls this function, it has to initialize
  34.     the XEM_IO structure ( => sample InitXEmReq(); ).
  35.     XEmulatorSetup() allocates and initializes emulator-private
  36.     data. A pointer to this data is stored in io->xem_console.
  37.     A comm-proggy isn't allowed to touch io->xem_console.
  38.     XEmulatorSetup() has to be the very first function call
  39.     after opening the library.
  40.  
  41.    INPUTS
  42.     xem_io - pointer to a properly initialized XEM_IO structure
  43.  
  44.    RESULTS
  45.     TRUE on success, FALSE on failure.
  46.  
  47.    SEE ALSO
  48.     xem.library/XEmulatorCleanup
  49.  
  50. xem.library/XEmulatorOpenConsole             xem.library/XEmulatorOpenConsole
  51.  
  52.    NAME
  53.     XEmulatorOpenConsole -- initializes screen and window
  54.  
  55.    SYNOPSIS
  56.     result = XEmulatorOpenConsole(xem_io)
  57.     D0                A0
  58.  
  59.     BOOL XEmulatorOpenConsole(struct XEM_IO *);
  60.  
  61.    FUNCTION
  62.     XEmulatorOpenConsole has to be called after a comm-proggy has
  63.     opened (or changed) its screen and/or window.
  64.     XEmulatorOpenConsole resets its internal data structure and
  65.     sets custom-fonts, special drawing modes, etc..
  66.     At this call, the emulator should allocate window-specific data
  67.     like history-buffers...
  68.  
  69.    INPUTS
  70.     xem_io - pointer to a properly initialized XEM_IO structure
  71.  
  72.    RESULTS
  73.     TRUE on success, FALSE on failure.
  74.  
  75.    SEE ALSO
  76.     xem.library/XEmulatorCloseConsole
  77.  
  78. xem.library/XEmulatorCloseConsole           xem.library/XEmulatorCloseConsole
  79.  
  80.    NAME
  81.     XEmulatorCloseConsole -- releases screen and window
  82.  
  83.    SYNOPSIS
  84.     XEmulatorCloseConsole(xem_io);
  85.                 A0
  86.  
  87.     VOID XEmulatorCloseConsole(struct XEM_IO *);
  88.  
  89.    FUNCTION
  90.        The comm-proggy wants to close its screen and/or window. It
  91.        gives the emulator the chance to free window-specific data.
  92.     
  93.    INPUTS
  94.     xem_io - pointer to a properly initialized XEM_IO structure
  95.  
  96.    RESULTS
  97.     Nothing returned.
  98.  
  99.    SEE ALSO
  100.     xem.library/XEmulatorOpenConsole
  101.  
  102. xem.library/XEmulatorCleanup                     xem.library/XEmulatorCleanup
  103.  
  104.    NAME
  105.     XEmulatorCleanup -- free internal structure used by the emulator.
  106.  
  107.    SYNOPSIS
  108.     XEmulatorCleanup(xem_io);
  109.             A0
  110.     VOID XEmulatorCleanup(struct XEM_IO *);
  111.  
  112.    FUNCTION
  113.    Frees internal structure used by the emulator.
  114.     The comm-proggy shouldn't call any XEmulator function
  115.     after this, except XEmulatorSetup...
  116.  
  117.    INPUTS
  118.     xem_io - pointer to a properly initialized XEM_IO structure
  119.  
  120.    RESULTS
  121.     Nothing returned.
  122.  
  123.    SEE ALSO
  124.     xem.library/XEmulatorSetup
  125.  
  126. xem.library/XEmulatorWrite                         xem.library/XEmulatorWrite
  127.  
  128.    NAME
  129.     XEmulatorWrite -- Write data into the window
  130.  
  131.    SYNOPSIS
  132.     XEmulatorWrite(xem_io, buffer, length);
  133.             a0    a1    d0
  134.  
  135.     VOID XEmulatorWrite(struct XEM_IO *, UBYTE *, LONG);
  136.  
  137.    FUNCTION
  138.     XemWrite() writes bytes of data to the window contained in the XEM_IO
  139.     structure. 'length' indicates the length of data to be written,
  140.     could also be -1 if 'buffer' is null terminated.
  141.     'buffer' is a pointer to the buffer to be written.
  142.  
  143.    INPUTS
  144.     xem_io - pointer to a properly initialized XEM_IO structure
  145.     buffer - pointer to the buffer
  146.     length - integer
  147.  
  148.    RESULTS
  149.     Nothing returned.
  150.  
  151. xem.library/XEmulatorSignal                       xem.library/XEmulatorSignal
  152.  
  153.    NAME
  154.     XEmulatorSignal -- Emulator private event has happened
  155.  
  156.    SYNOPSIS
  157.     result = XEmulatorSignal(xem_io, signal);
  158.     D0            A0    D0
  159.  
  160.     BOOL XEmulatorSignal(struct XEM_IO *, ULONG);
  161.  
  162.    FUNCTION
  163.     this function gives the emulator the ability to asynchronously
  164.     process data or to own an arexx-port.
  165.     the emulator puts his signal(s) prepared as a signal-mask
  166.     into *xem_io->xem_signal and the comm-proggy puts this signal-mask
  167.     into its main Wait() loop.
  168.     Everytime Wait() returns a signalset and the external
  169.     signal-mask is included, the comm-proggy has to call
  170.     XEmulatorSignal() with the signalset.
  171.     If the emulator returns FALSE, the comm-proggy should call
  172.     XEmulatorCloseConsole() followed by an XEmulatorCleanup().
  173.     After this, it could invoke its own emulator or startup
  174.     a previously used emulator...
  175.  
  176.    INPUTS
  177.     xem_io - pointer to a properly initialized XEM_IO structure
  178.     signal - integer
  179.  
  180.    RESULTS
  181.     TRUE on success, FALSE on failure.
  182.  
  183. xem.library/XEmulatorHostMon                     xem.library/XEmulatorHostMon
  184.  
  185.    NAME
  186.     XEmulatorHostMon -- let have a look at incoming serial data 
  187.  
  188.    SYNOPSIS
  189.     destinationLength = XEmulatorHostMon(xem_io, hostData, actual);
  190.         D0                A0    A1    D0
  191.  
  192.     ULONG XEmulatorHostMon(struct XEM_IO *, struct HostData *, ULONG);
  193.  
  194.    FUNCTION
  195.     hostdata is pointer to structure containing data, pointers and
  196.     flags to convert incoming serial data in pure ASCII text.
  197.     Actual is the number of bytes received from the serial device.
  198.     If hostData->Destination is non-NULL, this function
  199.     builds another string to contain the pure ASCII contents,
  200.     i.e. not including any ANSI ESC- or CSI control sequences.
  201.     This string is placed in hostData->Destination. hostData-Source
  202.     contents a pointer to the original data received from
  203.     the serial device.
  204.     It returns the actual number of bytes of data in
  205.     hostData->Destination in destinationLength.
  206.     HostData->InESC and hostData->InCSI are emulator private flags
  207.     to indicate there's a ANSI control sequence in process or not.
  208.     The comm-proggy isn't allowed to touch these flags at any time
  209.     except when allocating the structure and initializing it to FALSE.
  210.     At run time, it has only to support the hostData->Source and
  211.     hostData->Destination elements.
  212.  
  213.    NOTE
  214.     The emulator isn't allowed to change data in hostData->Source.
  215.  
  216.    WARNING
  217.     hostData->Destination has to have the same
  218.     dimension as hostData->Source!
  219.  
  220.    INPUTS
  221.     xem_io   - pointer to a properly initialized XEM_IO structure
  222.     hostdata - pointer to a HostData structure
  223.     actual   - integer
  224.  
  225.    RESULTS
  226.     destinationLength - the number of characters in the
  227.                         hostdata->Destination buffer, or 0 if
  228.                         hostdata was NULL.
  229.  
  230.  
  231. xem.library/XEmulatorUserMon                     xem.library/XEmulatorUserMon
  232.  
  233.    NAME
  234.     XEmulatorUserMon -- Decode single raw key input event to a string.
  235.  
  236.    SYNOPSIS
  237.     actual = XEmulatorUserMon(xem_io,buffer,length,intuimsg);
  238.     D0            A0    A1    D0    A2
  239.  
  240.     ULONG XEmulatorUserMon(struct XEM_IO *, UBYTE *, ULONG,
  241.                     struct IntuiMessage *);
  242.  
  243.    FUNCTION
  244.     This console function converts input events of type
  245.     IECLASS_RAWKEY to ANSI bytes, based on the emulator, and
  246.     places the result into the buffer.
  247.     This function also emulates the keyboard of the external 
  248.     emulator. For example it generates the PF keys of a VT terminal. 
  249.  
  250.    INPUTS
  251.     xem_io   - pointer to a properly initialized XEM_IO structure
  252.     buffer   - a byte buffer large enough to hold all anticipated
  253.                characters generated by this conversion.
  254.     length   - maximum anticipation, i.e. the buffer size in bytes.
  255.     intuimsg - a pointer to a valid (not ReplyMsg()'ed)
  256.                IntuiMessage structure
  257.  
  258.    RESULTS
  259.     actual - the number of characters in the buffer, or -1 if
  260.              a buffer overflow was about to occur.
  261.  
  262. xem.library/XEmulatorOptions                     xem.library/XEmulatorOptions
  263.  
  264.    NAME
  265.     XEmulatorOptions -- let the user to change options
  266.  
  267.    SYNOPSIS
  268.     result = XEmulatorOptions(xem_io);
  269.     D0            A0
  270.  
  271.     BOOL XEmulatorOptions(struct XEM_IO *);
  272.  
  273.    FUNCTION
  274.    tells the emulator to setup his options structure
  275.     and to call xem_io->xem_options().
  276.     xem_io->xem_options is 100% compatible to xpr_io->xpr_options.
  277.  
  278.    INPUTS
  279.     xem_io - pointer to a properly initialized XEM_IO structure
  280.  
  281.    RESULTS
  282.     TRUE on success, FALSE on failure.
  283.  
  284.  
  285. xem.library/XEmulatorClearConsole           xem.library/XEmulatorClearConsole
  286.  
  287.    NAME
  288.     XEmulatorClearConsole -- clear the display
  289.  
  290.    SYNOPSIS
  291.     XEmulatorClearConsole(xem_io);
  292.                 A0
  293.  
  294.     VOID XEmulatorClearConsole(struct XEM_IO *);
  295.  
  296.    FUNCTION
  297.     clear the screen and home the cursor.
  298.  
  299.    INPUTS
  300.     xem_io - pointer to a properly initialized XEM_IO structure
  301.  
  302.    RESULTS
  303.     Nothing returned.
  304.  
  305. xem.library/XEmulatorResetConsole           xem.library/XEmulatorResetConsole
  306.  
  307.    NAME
  308.        XEmulatorResetConsole -- resets the emulator
  309.  
  310.    SYNOPSIS
  311.     XEmulatorResetConsole(xem_io);
  312.                 A0
  313.  
  314.     VOID XEmulatorResetConsole(struct XEM_IO *);
  315.  
  316.    FUNCTION
  317.        XEmulatorResetConsole will clear the screen and home the cursor,
  318.     reset possible charsets, textstyles, etc..
  319.  
  320.    INPUTS
  321.     xem_io - pointer to a properly initialized XEM_IO structure
  322.  
  323.    RESULTS
  324.     Nothing returned.
  325.  
  326. xem.library/XEmulatorResetTextStyles     xem.library/XEmulatorResetTextStyles
  327.  
  328.    NAME
  329.     XEmulatorResetTextStyles -- resets text-styles
  330.  
  331.    SYNOPSIS
  332.     XEmulatorResetTextStyles(xem_io);
  333.                 A0
  334.  
  335.     VOID XEmulatorResetTextStyles(struct XEM_IO *);
  336.  
  337.    FUNCTION
  338.     When you're using an ANSI emulator, it can happen that
  339.     your BBS enables blink-invers-bold... text attributes.
  340.     XEmulatorResetTextStyles disables such alien things
  341.     to human readable text..
  342.  
  343.    INPUTS
  344.     xem_io - pointer to a properly initialized XEM_IO structure
  345.  
  346.    RESULTS
  347.     Nothing returned.
  348.  
  349. xem.library/XEmulatorResetCharset           xem.library/XEmulatorResetCharset
  350.  
  351.    NAME
  352.     XEmulatorResetCharset -- resets charset
  353.  
  354.    SYNOPSIS
  355.     XEmulatorResetCharset(xem_io);
  356.                 A0
  357.  
  358.     VOID XEmulatorResetCharset(struct XEM_IO *);
  359.  
  360.    FUNCTION
  361.     When you're useing an Amiga- or VTxxx emulator, this function
  362.     disables alternative charsets and steps back to the `normal'
  363.     ISO Latin-1 or DEC charset.
  364.  
  365.    INPUTS
  366.     xem_io - pointer to a properly initialized XEM_IO structure
  367.  
  368.    RESULTS
  369.     Nothing returned.
  370.  
  371. xem.library/XEmulatorGetFreeMacroKeys   xem.library/XEmulatorGetFreeMacroKeys
  372.  
  373.    NAME
  374.     XEmulatorGetFreeMacroKeys -- return free macro keys
  375.  
  376.    SYNOPSIS
  377.     freeKeys = XEmulatorGetFreeMacroKeys(xem_io, qualifier);
  378.     D0                    A0    D0
  379.  
  380.     ULONG XEmulatorGetFreeMacroKeys(struct XEM_IO *, ULONG);
  381.  
  382.    FUNCTION
  383.    returns a bitmask containing the free macro-keys specified
  384.    by qualifier. There are the following qualifier-types:
  385.     XMKQ_NONE, XMKQ_SHIFT, XMKQ_ALTERNATE, XMKQ_CONTROL
  386.  
  387.    INPUTS
  388.     xem_io - pointer to a properly initialized XEM_IO structure
  389.  
  390.    RESULTS
  391.        freeKeys - integer
  392.  
  393.    SEE ALSO
  394.     xem.library/XEmulatorMacroKeyFilter
  395.  
  396. xem.library/XEmulatorMacroKeyFilter       xem.library/XEmulatorMacroKeyFilter
  397.  
  398.    NAME
  399.     XEmulatorMacroKeyFilter -- install macro-key definitions
  400.  
  401.    SYNOPSIS
  402.     result = XEmulatorMacroKeyFilter(xem_io,keys);
  403.     D0                A0    A1
  404.  
  405.     BOOL XEmulatorMacroKeyFilter(struct XEM_IO *, struct List *);
  406.  
  407.    FUNCTION
  408.     Tells the emulator to accept a new list. If list is NULL,
  409.     the emulators key-filter is disabled.
  410.     list is a standard Amiga List structure. The nodes attached to
  411.     this list are called `struct XEmulatorMacroKey'.
  412.     Their elements are:
  413.  
  414. struct XEmulatorMacroKey {
  415.   struct MinNode xmk_Node;
  416.   UWORD    xmk_Qualifier;    /* see below */
  417.   UBYTE    xmk_Type;    /* see below */
  418.   UBYTE    xmk_Code;    /* raw or cooked key-code */
  419.   APTR    xmk_UserData;    /* comm-proggy private data */
  420.             /* could be a function ptr or a modem cmd */
  421. };
  422.  
  423. /*----- Qualifiers for XMK_QUALIFIER -----*/
  424. #define XMKQ_NONE      0 /* execute this key if no qualfier is pressed */
  425. #define XMKQ_SHIFT     1 /* execute this key if a shift key is pressed */
  426. #define XMKQ_ALTERNATE 2 /* execute this key if  an alt key is pressed */
  427. #define XMKQ_CONTROL   3 /* execute this key if control key is pressed */
  428.  
  429. /*----- Types for XMK_TYPE -----*/
  430. #define XMKT_IGNORE 1    /* ignore this key definition */
  431. #define XMKT_RAWKEY 2    /* xmk_Code is raw */
  432. #define XMKT_COOKED 3    /* xmk_Code is cooked */
  433.  
  434.  
  435.    INPUTS
  436.     xem_io - pointer to a properly initialized XEM_IO structure
  437.  
  438.    RESULTS
  439.     TRUE on success, FALSE on failure.
  440.  
  441.    SEE ALSO
  442.     xem.library/XEmulatorGetFreeMacroKeys
  443.  
  444. xem.library/XEmulatorInfo                           xem.library/XEmulatorInfo
  445.  
  446.    NAME
  447.     XEmulatorInfo -- return info about the emulator
  448.  
  449.    SYNOPSIS
  450.     XEmulatorInfo(xem_io, type);
  451.             A0    d0
  452.  
  453.     VOID XEmulatorInfo(struct XEM_IO *, ULONG);
  454.  
  455.    FUNCTION
  456.     This function returns selected pointers to structures or buffers
  457.     defined in the external emulator.
  458.     Currently defined info-types:
  459.  
  460.     XEMI_CURSOR_POSITION
  461.     returns the actual cursor-position. Home is 1,1.
  462.  
  463.     XEMI_CONSOLE_DIMENSIONS
  464.     returns the console dimensions in columns and lines.
  465.  
  466.    INPUTS
  467.     xem_io - pointer to a properly initialized XEM_IO structure
  468.     type - integer
  469.  
  470.     SAMPLE-CODE
  471.  
  472.     /* for use in the emulator */
  473.  
  474. LONG __saveds __asm XEmulatorInfo(register __a0 struct XEM_IO *io, register __d0 ULONG type)
  475. {
  476.    struct ASCIIConsole *con = (struct ASCIIConsole *)io->xem_console;
  477.    LONG result = -1;
  478.  
  479.    if(con != NULL)
  480.    {
  481.       switch(type)
  482.       {
  483.          case XEMI_CURSOR_POSITION:
  484.             result = XEMI_CREATE_POSITION(con->col, con->row);
  485.          break;
  486.  
  487.          case XEMI_CONSOLE_DIMENSIONS:
  488.             result = XEMI_CREATE_DIMENSIONS(con->columns, con->rows);
  489.          break;
  490.  
  491.       }
  492.    }
  493.    return(result);
  494. }
  495.  
  496.  
  497.     /* for use in comm-proggy */
  498.  
  499.    {
  500.       LONG result;
  501.  
  502.         /* get actual cursor position */
  503.  
  504.       result = XEmulatorInfo(XEmActualVars, XEMI_CURSOR_POSITION);
  505.       if(result != -1)
  506.       {
  507.          WORD cursorX, cursorY;
  508.  
  509.          cursorX = XEMI_EXTRACT_X_POSITION(result);    /* Origin is 1 */
  510.          cursorY = XEMI_EXTRACT_Y_POSITION(result);    /* Origin is 1 */
  511.          .
  512.          .
  513.          .
  514.       }
  515.    }
  516.  
  517.  
  518.    {
  519.       LONG result;
  520.  
  521.       result = XEmulatorInfo(XEmActualVars, XEMI_CONSOLE_DIMENSIONS);
  522.       if(result != -1)
  523.       {
  524.          WORD lines, columns;
  525.  
  526.             /* get columns and lines */
  527.  
  528.          columns = XEMI_EXTRACT_COLUMNS(result);
  529.          lines   = XEMI_EXTRACT_LINES(result);
  530.          .
  531.          .
  532.          .
  533.       }
  534.    }
  535.  
  536.  
  537.    RESULTS
  538.     -1 on failure
  539.  
  540. xem.library/XEmulatorPreferences             xem.library/XEmulatorPreferences
  541.  
  542.    NAME
  543.     XEmulatorPreferences -- load or save preferences file
  544.  
  545.    SYNOPSIS
  546.     XEmulatorPreferences(xem_io, fileName, mode);
  547.                 A0    a1    d0
  548.  
  549.     VOID XEmulatorPreferences(struct XEM_IO *, STRPTR, ULONG);
  550.  
  551.    FUNCTION
  552.     Depending on the mode, XEmulatorPreferences loads or saves a
  553.     preferences-file named fileName.
  554.     In case of XEM_PREFS_RESET, the emulator steps back to its
  555.     internal presets; the fileName is ignored and should be NULL.
  556.  
  557.     The preferences-files are placed in ENV:xem
  558.     A preferences-file-name consists of the library-name
  559.     without the `.library` extension.
  560.     a preferences-file for an xemascii.library would be
  561.     called xemascii..
  562.  
  563. /*----- Modes for XEmulatorPreferences -----*/
  564. #define XEM_PREFS_RESET    0    /* Reset to builtin defaults    */
  565. #define XEM_PREFS_LOAD    1    /* Load preferences from file    */
  566. #define XEM_PREFS_SAVE    2    /* Save preferences to file    */
  567.  
  568.    INPUTS
  569.     xem_io   - pointer to a properly initialized XEM_IO structure
  570.     fileName - STRPTR
  571.     mode     - integer
  572.  
  573.    RESULTS
  574.     TRUE on success, FALSE on failure.
  575.